\documentclass[12pt,a4paper]{scrbook}

%
%Header
%
%\usepackage{fancyhdr}
%\setlength{\headheight}{15.2pt}
\usepackage{scrpage2}
\usepackage{listings}
\usepackage{geometry}
\lstset{frame=single, basicstyle=\ttfamily, tabsize=4}
\cfoot{}
\pagestyle{empty}

%\fancyhf{}

%\fancyhead[%\fancyfoot[C]{}


\begin{document}

\title {BTASM Language Specification}
\date {Revision 0 - April 4, 2012}
\author {Jonathan MacMillan \\(jonathan.macmillan@yale.edu)}
\maketitle

\frontmatter
\setcounter{page}{1}
\tableofcontents


\chapter*{Preface}
\addcontentsline{toc}{chapter}{Preface}
\pagestyle{scrheadings}
\rohead{\thepage}
\rehead{PREFACE}
\lohead{PREFACE}
\lehead{\thepage}
\cfoot{}
\ofoot{}
%\fancyhead[RO]{\thepage}
%\fancyhead[LO] {PREFACE}
%\fancyhead[RE] {PREFACE}
%\fancyhead[LE]{\thepage}
\section*{Introduction}

Battle Tag is a laser tag system designed and marketed by UbiSoft.  It was released in a
limited market (ie, Texas and Canada) near the end of 2010.  Since then, the system has
not been released in a larger market.  It appears to have been abandoned by UbiSoft shortly
thereafter, and (as of the creation of this document) none of the equipment can be purchased
from UbiSoft's website.

The game itself consists of infra-red ``laser" guns, sensor vests, RFID-enabled ``bases", and
the UbiConnect, a USB peripheral which communicates with the guns using an unknown radio
technology.  The computer that is connected to the UbiConnect manages all aspects of play 
(except, of course, those that it offloads to the weapons themselves) and is called the Game
Master (henceforth referred to as the GM).

Support for the product seems to be very limited.  The new equipment being sold by other
vendors in what seems to be a liquidation sale comes with a 90-day manufacturer warranty, 
which is not being honored by UbiSoft (I contacted them concerning a problem with one of my vests, 
and was told that they don't have the resources to support the product anymore.  I will hopefully be
able to resolve the issue with the party I purchased the product from, so I did not pursue further to
force UbiSoft to honor the warranty they provided.)  Be sure to thoroughly test the
equipment within the 90-day period (better yet, within the seller's return period), as the first
 sensor vest that I purchased was faulty.
There is no easy way to get the equipment in the United States - 1saleaday has been selling
vests and guns through Buy.com  for around \$65 with shipping for some time.  The expansion kits are
 nearly impossible to find - I could only source them from Amazon Canada, which does not allow 
 importation of video games to the United States.  There is a person who posted to the UbiSoft forum
 thread about open-sourcing BattleTag\footnote{See the thread at \\
 http://forums.ubi.com/showthread.php/660186-Battle-Tag-now-obsolete-Please-Open-Source-the-software!}
who claimed as of April 2012 to know where to get some clearance-priced Expansion Kits in the
Houston area.

\section*{Purpose}

The purpose of this document is to elucidate the bytecode and source language that is used to 
control the 
guns during gameplay.  This information has been gleaned from the bytecode and associated
source files provided with the BattleTag software.  Anyone who wishes to obtain this 
software must purchase BattleTag equipment - the software is not available legally (to
my knowledge) save on the CD-ROM that accompanies the game.

Every time a game is initiated, the GM broadcasts a bytecode
to all of the guns that are involved in the game.  This bytecode is stored on the PC in Lua tables
as a comma-separated sequence of hex bytes (though there is no reason why decimal bytes
couldn't be used, if one were feeling masochistic).  The bytecode appears to be almost completely
responsible for the functioning of the device in game - the full workings of each gameplay
mode appear to be represented in the bytecode files rather than in the device firmware.

UbiSoft has rather oddly chosen to leave the non-assembled source files for all of the
bytecodes in the distributed version of the game.  This golden opportunity has allowed
reverse-engineering the bytecode to take orders of magnitude less time than it would
have otherwise.  The language used seems to be a special language developed in-house at
UbiSoft.  It is a simple event-driven imperative language, with special language features to control
different elements of the weapon.  There is a slight bit of work that the assembler needs 
to do in order to translate between the source code and the bytecode.  In fact, it is very
straightforward to write bytecode and upload it to the device (by hijacking the game's built-in
upload routines).

There appears to be no CRC or consistency check of any sort on the weapons or the GM.  In fact,
it is perfectly possible to upload broken code to the device.  It appears that simply turning
the device off and on clears the flashed bytecode and returns the device to a factory state.
This, however, has not been thoroughly tested, and it is not recommended that code by written
with the intention of interfering with the actual device firmware (though such modification 
should be possible through editing the GM's Lua files).

%The bytecode described here is obviously that used by the weapons.  The canonical BTASM
% language,
%however, differs from the UbiSoft-style BTASM.  The BTASM compiler has a flag
%(-U) that can parse UbiSoft-style BTASM\footnote{This flag is included mainly for 
%testing against UbiSoft-style files}; canonical BTASM is used by default, and should 
%be used unless there is a particular reason not to do so.   

This document does not go into great detail concerning the code that the GM must run to keep the
game working.  The basics are covered near the end in order to facilitate testing bytecodes on
the device.  The GM code varies less than one might expect from game type to game type, and is
mainly concerned with overall control and scoring, though it can also serve a more integral function.
In the game ``The Wolf" that is included with the bytecode, the GM is responsible for setting which
player is the wolf, and changing that player from time to time.  If there is interest, I may cover
GM programming in more detail in another book.  The information in this book should be enough to
create a new game and set it up, though without the scoreboard features that are present in the
built-in games.
 
\section*{Disclaimer}

%The author makes no
%guarantee that any of the information presented in this document is accurate.  
Everything in this document is presented on an ``as-is" and ``with all faults" basis.  The 
author is not liable
for any damage to equipment or persons that is caused by any use, modification, or 
dissemination of the information presented in this document.  You
are solely responsible for determining the applicability and compatibility of this
information with and to your equipment, and for the protection of yourself and your 
equipment.

\section*{Acknowledgements}

Thanks to BL Martech, who alerted me to the fact that the Battle Tag distribution included
Lua source files.  Thanks, also, to the developers at UbiSoft, who left a veritable roadmap for
us to follow.  
Thanks, also, to the members of the UbiSoft forum who compelled me to start the journey to understand
and help others to understand the inner workings of BattleTag.
Thanks to ??? who purchased and shipped me a few Expansion Packs.
All thanks, of course, are given to God, who granted me a mind and a will to better
understand this part of His creation.  May this work glorify Him alone.


\rohead {\thepage}
\lohead {\rightmark}
\rehead {\leftmark}
\lehead {\thepage}

\mainmatter

\chapter{The Source Language}

This chapter gives an overview of the BTASM source language; that is, the language in which
BTASM programs are written before they are compiled into the bytecode (which is detailed in 
Chapter 3).

\section{Language properties}

BTASM source is whitespace-agnostic.  Control structures are defined explicitly, though indentation 
is
recommended in order to facilitate comprehension of control structures.  BTASM is case-sensitive;
all language commands and named constants contain only uppercase characters.  
Variables can contain upper- and lowercase alphanumeric charaters and the underscore character.

\section{Source file structure}
BTASM source language files are very simple in nature.  They consist of:
\begin{itemize}
\item A resource block (only in bytecode)
\item A variable declaration block
\item Optional function declarations
\item A required initial state
\item Optional additional states
\end{itemize}

These parts of a source file must appear in this order in an BTASM source file.  
\\\\
The resource block never appears in the BTASM source files -- it is instead generated by the btasm
compiler from
the rest of the source file and prepended to the beginning of the bytecode.  The resource block is 
a list of all the sound and animation resources that the gun uses for this program.  They appear in
the order of their first appearance in the file, ""but this is not necessary  (is it?).**  
The block is preceded by a byte which lists how many resources there are in this file.  A simple
bytecode may only need three or four sound/animation resources, while a complicated bytecode may use
twenty or thirty.  **While it is possible to use at least twenty, the maximum possible number is 
not known.**  

It is essential to note that, while these resources are represented in the source files with 
particular names that do not vary from file to file, the integer values that represent these 
different resources do vary, depending on the order that they appear in the resource block.  A 
convenient way to think about it is a simple map, where the values are incremented by one each time
a new key is inserted.  Therefore, the particular mapping of the sound DEAD might not be the same 
between two source files, but it will not change within a bytecode file.

The variable declaration block consists of a newline-separated list of variable expressions
which define a variable by name and determine its relationship to the GM.  All variables are 
**32-bit integers** (CHECK THIS).  

By default, all variables are declared as global variables in the scope of the gun program.
The scope of the variable as it relates to the GM can be modified with the following keywords:
\begin{itemize}
\item CONFIG (the variable is configured by the GM at the beginning of the game)
\item SEND (the variable is sent to the GM in regular updates)
\item RECEIVE (the variable is sent to the gun from the GM in regular updates)
\end{itemize}

Variables of the different types can be declared in any order.  No variable can be declared
with more than one attribute type: thus \lstinline|VAR foo SEND, CONFIG| is an invalid
declaration.  All of these variables exist in a global namespace.  There are no limited-scope 
variables.  Variables cannot be declared outside of the variable declaration block.  

\begin{figure}[h]
\begin{lstlisting}
VAR a	SEND
VAR b
VAR c   RECEIVE
VAR d	CONFIG
VAR e	SEND
\end{lstlisting}
\caption{A valid variable block in a BTASM source program} 
\end{figure}

\ \\

The optional function declarations follow the variable declaration block.  A function definition
consists of a special keyword (FUN) and a name.  There is no separation function declaration - the
function definition serves as the declaration.  Therefore, function declarations *must/should* be
placed at the beginning of the source file/before they are first
used in the program.  The variable and function name-spaces do not
conflict in the btasm compiler or in the bytecode.  
If no functions are needed, than none need be declared.  Note 
that these functions are decidedly non-functional, since they depend on global values, and neither
accept arguments or return values.  They would be better referred to as procedures -- following the
syntax of the source language, we will refer to them as functions.


  

\begin{figure}[h]
\begin{lstlisting}
FUNCTION foo
	HUD_ICON_ON BULLET
	HUD_ICON_ON LIFE
END_FUNCTION
\end{lstlisting}
\caption{A valid function definition in a BTASM source program} 
\end{figure}


Event states are the main drivers of the gun's action.  The control flow of a BTASM program can be
conceptualized as a state machine.  The gun begins the game in an initial state (denoted by 
\texttt{FIRST\_STATE}), in which it responds to environmental stimuli.  At points, the gun can switch
states, and respond differently to the same stimuli.  This paradigm will be familiar to anyone who
has programmed embedded devices.

The possible events that a particular state can respond to are (at least): (??? - check the 
bytecodes to see if there are more)
\begin{itemize}
\item \texttt{ANIM\_FINISHED} - finished HUD animation
\item \texttt{BUTTON\_1\_JUST\_PRESSED} - pressed button below HUD
\item \texttt{BUTTON\_2\_JUST\_PRESSED} - pressed trigger
\item \texttt{BUTTON\_3\_JUST\_PRESSED} - pressed RFID button
\item \texttt{DATA\_CHANGE} - GM has changed variable(s) declared with the \texttt{RECEIVE} attribute
\item \texttt{ENTER\_STATE} - code run upon entering a state
\item \texttt{HIT} - hit by another gun
\item \texttt{TIMER} - probably responds to end of TIMER that was set earlier
\item \texttt{TICK} - do something on each tick of the clock (what clock???)
\end{itemize}

Each of these events, when called, runs a block of code which can do anything that can be done
in a function.  It can \texttt{GOTO} an alternate state; call a function; change variables; or
simply do nothing.  Events cannot be declared more than once per state.

The state namespace does not conflict with the function namespace or the variable namespace.  It is
possible to have a variable named foo, a function named foo, and a state named foo (this is, however,
not recommenced, and the compiler will print a warning if it detects double-naming).  Analogously,
states, functions, and variables are all numbered from 0 in the bytecode.  The command determines
which table is used for lookup.


\begin{figure}[h]
\begin{lstlisting}
STATE foo
FIRST_STATE

	EVENT BUTTON_1_JUST_PRESSED
		HUD_ICON_ON BULLET
	END_EVENT

	EVENT BUTTON_3_JUST_PRESSED
		HUD_ICON_OFF BULLET
	END_EVENT

END_STATE
\end{lstlisting}
\caption{A valid state definition in an UbiSoft-style BTASM program} 
\end{figure}

\begin{figure}[h]
\begin{lstlisting}

VAR a SEND
VAR b 

FUNCTION foo
	HUD_ICON_ON BULLET
	HUD_ICON_OFF LIFE
END_FUNCTION

FUNCTION bar
	HUD_ICON_ON LIFE
	HUD_ICON_OFF BULLET
END_FUNCTION
	
STATE baz
FIRST_STATE

	EVENT BUTTON_1_JUST_PRESSED
		foo		//call function foo
	END_EVENT

	EVENT BUTTON_3_JUST_PRESSED
		bar		//call function bar
	END_EVENT

END_STATE
\end{lstlisting}
\caption{A valid BTASM source program} 
\end{figure}
\newpage

\section{Source language commands}

%%%%%%
%Conventions
%%%%%%
\subsection{Conventions}
Arguments are enclosed in [...] if they change.  Keywords are not enclosed in brackets and are not
included in the arguments lists that follow each command.
Items enclosed in $<$...$>$ are optional arguments.

\begin{itemize}
\item $[$ANIMID$]$ is identifier that represents a sound. (See section \ref{sec:resourcetable} and 
		table \ref{Resource table})
\item $[$ICONID$]$ is identifier that represents an icon on the HUD. 
		(See section \ref{sec:icontable})
\item $[$ID$]$ is an identifier (such as \texttt{foo} or \texttt{bar} or \texttt{init\_game}.)
\item $[$INT$]$ is a 1-byte integer.  
\item $[$LONGINT$]$ is a 2-byte integer, with the upper 8 bits of the value coming in the first byte 
		and the lower 8 bits of the value coming in the second.
\item $[$SNDID$]$ is identifier that represents a sound. (See section \ref{sec:resourcetable} and 
		table \ref{Resource table})

\end{itemize}




\subsection{Declarations}

\subsubsection{VAR [ID] $<$[VARATTR]$>$} 
Declares a global variable.  (See table \ref{sec:compconsts} for descriptions of the constants).
\begin{itemize}
\item A1 = variable identifier
\item A2 = variable attribute (see table \ref{sec:compconsts})
\begin{itemize}
\item \texttt{SEND}
\item \texttt{RECEIVE}
\item \texttt{CONFIG}
\end{itemize}
\end{itemize}

\subsubsection{FUNCTION [ID] ... END\_FUNCTION}
Declares a function.
\begin{itemize}
\item A1 = function identifier
\end{itemize}

\subsubsection{STATE [ID] $<$FIRST\_STATE$>$ ... END\_STATE}
Declares a new state.  If FIRST\_STATE is present, then this is the initial state.
Otherwise, it is a standard state.
\begin{itemize}
\item A1 = state identifier
\end{itemize}
NB - There can be only one initial state per program.

\subsubsection{EVENT [EVENTTYPE] ... END\_EVENT}
Declares a new event in a state.  (See table \ref{sec:eventtypeconsts} for descriptions.)
Event types:
\begin{itemize}
\item \texttt{BUTTON\_1\_JUST\_PRESSED}
\item \texttt{BUTTON\_2\_JUST\_PRESSED}
\item \texttt{BUTTON\_3\_JUST\_PRESSED}
\item \texttt{TIMER}
\item \texttt{TICK}
\item \texttt{HIT}
\item \texttt{ENTER\_STATE}
\item \texttt{ANIM\_FINISHED}
\item \texttt{DATA\_CHANGE}
\end{itemize}

\subsection{Control flow}

\subsubsection{GOTO [ID]}
Switch to a different state.  That state's ENTER\_STATE event will be executed.?????
\begin{itemize}
\item A1 = identifier of state to move to
\end{itemize}

\subsubsection{IF [ID] [COMPARATOR] [ID or LONGINT] ... $<$ELSE ...$>$ END\_IF }
Compare two values and branch depending on the result of the comparison.
\begin{itemize}
\item A1 = identifier of left-side comparison variable
\item A2 = comparison function (SUP, INF, COMP, or DIFF) (see table \ref{sec:compconsts})
\item A3 = integer or identifier to variable to compare with (right side)
\end{itemize}
NB - if the \texttt{ELSE} branch is empty, do not include the material in angle brackets.
To have a negated \texttt{IF} statement, leave the \texttt{IF} branch empty and insert
code in the \texttt{ELSE} branch.

\subsubsection{[ID]}
Call a function.
\begin{itemize}
\item A1 = identifier of function to call
\end{itemize}


%%%%%%%%%%%
%MUTATION
%%%%%%%%%%%
\subsection{Mutation/settings}

%%%SET
\subsubsection{SET [ID] [ID or LONGINT]}
Set the value of a variable.
\begin{itemize}
\item A1 = identifier of the variable to set
\item A2 = integer or identifier of variable that contains value to set A1 to
\end{itemize}

%%%%INC/DEC
\subsubsection{DEC [ID]}
Decrement a variable.
\begin{itemize}
\item A1 = identifier of variable to decrement
\end{itemize}

\subsubsection{INC [ID]}
Increment a variable
\begin{itemize}
\item A1 = identifier of variable to increment
\end{itemize}

%TEAM
\subsubsection{SET\_TEAM [ID]}
Set the team number for this device.
\begin{itemize}
\item A1 = identifier of the variable that holds the team number
\end{itemize}

%HARNESS
\subsubsection{SET\_HARNESS [INT]}
Set whether the harness is used or not in this game.
\begin{itemize}
\item A1 = 0 if harness is not used; 1 if harness is used
\end{itemize}






%%%%%%%%
%OUTPUT
%%%%%%%%
\subsection{Output}

%%MOTOR
\subsubsection{MOTOR [INT]}
Run the device motor.
\begin{itemize}
\item A1 = number of centiseconds to run the motor
\end{itemize}

%FLASH COLORS
\subsubsection{FLASH\_RED [INT]}
Flash a red light.

\begin{itemize}
\item A1 = ???
\end{itemize}
\subsubsection{FLASH\_GREEN [INT]}
Flash a green light.

\begin{itemize}
\item A1 = ???
\end{itemize}

\subsubsection{FLASH\_ORANGE [INT]}
Flash an orange light.  This is implemented by flashing a red then a green light.

\begin{itemize}
\item A1 = ???
\end{itemize}

%%%%%SND
\subsubsection{SND [SNDID]}
Play a sound.
\begin{itemize}
\item A1 = the sound-ID of the sound to play 
\end{itemize}

\subsubsection{SND\_PRIO [SNDID]}
Play a sound (with priority???).
\begin{itemize}
\item A1 = the sound-ID of the sound to play
\end{itemize}

%%IR
\subsubsection{IR}
Flash the IR transmitter in the gun.

%%%ANIM
\subsubsection{ANIM [ANIMID]}
Display an animation on the HUD.  (See \ref{sec:animtab} for a list of resource constants;
see \ref{sec:resourcetable} for information about the resource table.)
\begin{itemize}
\item A1 = animation-ID of the resource to display.  Must be an animation (\texttt{0x41,...}).
\end{itemize}

\subsubsection{ANIM\_LOOP [ANIMID]}
Loop an animation on the HUD.  (See \ref{sec:animtab} for a list of resource constants;
see \ref{sec:resourcetable} for information about the resource table.)
\begin{itemize}
\item A1 = animation-ID of the resource to display.  Must be an animation (\texttt{0x41,...}).
\end{itemize}


%ANIM_OFF
\subsubsection{ANIM\_OFF}
TODO - what does this do???
Turn off (the????) animation on the HUD.

%%%LED
\subsubsection{LED\_ON [INT] 0x01}
Turn on the LEDs on the harness.
\begin{itemize}
\item A1 = length of time to turn on LED
\end{itemize}
NB - if the 0x01 argument is set to 0x00, then the bytecode is the same as the bytecode for 
\texttt{LED\_INFINITE [INT]}.

\subsubsection{LED\_INFINITE [INT]}
Blink the LEDs on the harness until LED\_OFF is called.
\begin{itemize}
\item A1 = length of time of one-half of an LED off-on cycle
\end{itemize}

\subsubsection{LED\_OFF}
Stop the LEDs on the harness from blinking.



%%%DIGIT
\subsubsection{HUD\_DIGIT [ID or INT]}
Display a digit (between 0 and 19) on the HUD. 
\begin{itemize}
\item A1 = identifier of variable or immediate value to display
\end{itemize}

\subsubsection{HUD\_DIGIT\_BLINK [ID or INT]}
Blink a digit (between 0 and 19) on the HUD. 
\begin{itemize}
\item A1 = identifier of variable or immediate value to display
\end{itemize}

\subsubsection{HUD\_DIGIT\_OFF}
Stop displaying a digit on the HUD.



%%%JAUGE
\subsubsection{HUD\_JAUGE [ID or INT]}
Display a value on the gauge.  Valid values are between 1 and 6.  Anything greater
than 6 will cause the gauge to display a value of 0.  
\begin{itemize}
\item A1 = identifier of variable or immediate value to display
\end{itemize}
NB - this can also be called with \texttt{HUD\_GAUGE}.

\subsubsection{HUD\_JAUGE\_BLINK [ID or INT]}
Blink a value on the gauge.  Valid values are between 1 and 6.  Anything greater
than 6 will cause the gauge to display a value of 0.  
\begin{itemize}
\item A1 = identifier of variable or immediate value to display
\end{itemize}
NB - this can also be called with \texttt{HUD\_GAUGE\_BLINK}.

%%%ICON
\subsubsection{HUD\_ICON\_ON [ICONID]}
Turn on one of the HUD icons.
\begin{itemize}
\item A1 = icon to modify (see table \ref{sec:iconconstants})
\begin{itemize}
\item \texttt{LIFE}
\item \texttt{BULLET}
\item \texttt{GOAL}
\end{itemize}
\end{itemize}
NB - there are no icon-IDs for the UbiConnect and the power icons.  You should not try to 
modify these yourself unless you know what you are doing.

\subsubsection{HUD\_ICON\_OFF [ICONID]}
Turn off one of the HUD icons.
\begin{itemize}
\item A1 = icon to modify (see table \ref{sec:iconconstants})
\begin{itemize}
\item \texttt{LIFE}
\item \texttt{BULLET}
\item \texttt{GOAL}
\end{itemize}
\end{itemize}
NB - there are no icon-IDs for the UbiConnect and the power icons.  You should not try to 
modify these yourself unless you know what you are doing.

%%%%%%%%%%%%%
%RFID
%%%%%%%%%%%%%
\subsection{RFID commands}

\subsubsection{RFID\_SCAN [ID]}
Perform a RFID scan.
\begin{itemize}
\item A1 = identifier of the variable in which to store the status of the scan.  Will be set to 0 
		upon failure, 1 upon success.
\end{itemize}

\subsubsection{RFID\_TYPE\_MAJOR [ID]}
Get the type of the base scanned.
\begin{itemize}
\item A1 = identifier of the variable in which to store the type
\end{itemize}

\subsubsection{RFID\_TYPE\_MINOR [ID]}
Get the specific ID of the base scanned (ie, is it T-Base 1 or T-Base 2).
\begin{itemize}
\item A1 = identifier of the variable in which to store the type
\end{itemize}














\chapter{The Bytecode}
This chapter contains a definition of each of the operations in the BTASM bytecode, along with an
explanation of their operation.  This chapter explains the bare mechanics of the bytecode, not
the syntax and semantics of the associated BTASM source language.  Do not confuse the mnemonics
used here with the keywords in the source language described in Chapter 2.

%%%%%%%%%%%%%%%%%
%INSTRUCTION SET
%%%%%%%%%%%%%%%%%
\section{Instruction set}

\subsection{Conventions}
\begin{itemize}
\item $[$EVENTCODE$]$ is a byte that represents a given event in a state. (See 
		table \ref{sec:eventtypeconsts})
\item $[$FUNIDX$]$ is an index into the function table. (See section \ref{sec:funstatetables})
\item $[$INT$]$ is a 1-byte integer.  
\item $[$LONGINT$]$ is a 2-byte integer, with the upper 8 bits of the value coming in the first byte 
		and the lower 8 bits of the value coming in the second.
\item $[$STATEIDX$]$ is an index into the state table. (See section \ref{sec:funstatetables})
\item $[$RESIDX$]$ is an index into the resource table. (See section \ref{sec:resourcetable} and 
		table \ref{Resource table})
\item $[$VARIDX$]$ is an index into the variable table. (See section \ref{sec:vartable})
\end{itemize}



\subsection{Declarations}

\subsubsection{0xcc - VAR [0,1,2,3]} 
Declares a global variable.  (See table \ref{sec:compconsts} for descriptions of the constants).
\begin{itemize}
\item 0 = no attributes (local)
\item 1 = \texttt{SEND}
\item 2 = \texttt{RECEIVE}
\item 3 = \texttt{CONFIG}
\end{itemize}

\subsubsection{0xd0 - FUNCTION [FUNIDX] [INT]}
Declares a function
\begin{itemize}
\item A1 = function identifier (non-repeated ascending integers)
\item A2 = size of function in bytes (maximum value of 256 - not counting this declaration)
\end{itemize}
NB - this is an overloaded instruction that is also used for function calls with a different type
signature

\subsubsection{0xd2 - STATE FIRST\_STATE [STATEIDX] [LONGINT]}
Declares a new (initial) state
\begin{itemize}
\item A1 = state identifier (non-repeated ascending integers)
\item A2 = size of the state in bytes (not counting this declaration)
\end{itemize}
NB - There can be only one initial state per program.

\subsubsection{0xc7 - STATE [STATEIDX] [LONGINT]}
Declares a new (non-initial) state
\begin{itemize}
\item A1 = state identifier (non-repeated ascending integers)
\item A2 = size of the state in bytes (not counting this declaration)
\end{itemize}
NB - Though there are different bytecodes for the initial state and a regular state,
the state identifiers must be unique for each different state.

\subsubsection{[EVENTCODE] - EVENT [EVENTCODE] [INT]}
Declares a new event in a state.  (See table \ref{sec:eventtypeconsts} for descriptions.)
Event types:
\begin{itemize}
\item \texttt{0x00 = BUTTON\_1\_JUST\_PRESSED}
\item \texttt{0x01 = BUTTON\_2\_JUST\_PRESSED}
\item \texttt{0x02 = BUTTON\_3\_JUST\_PRESSED}
\item \texttt{0x09 = TIMER}
\item \texttt{0x0a = TICK}
\item \texttt{0x0b = HIT}
\item \texttt{0x0c = ENTER\_STATE}
\item \texttt{0x0e = ANIM\_FINISHED}
\item \texttt{0x0f = DATA\_CHANGE}
\end{itemize}
The second argument is the length of the event code in bytes (not counting this declaration)

\subsection{Control flow}

\subsubsection{0xc3 - GOTO [STATEIDX]}
Switch to a different state.  That state's ENTER\_STATE event will be executed.?????
\begin{itemize}
\item A1 = index in state table to move to
\end{itemize}

\subsubsection{0xc4 - IF [VARIDX] 0x01 [LONGINT] [INT] [IF branch len]...[ELSE branch len]...}
\subsubsection{0xc4 - IF [VARIDX] 0x00 [VARIDX] [INT]...[IF branch len]...[ELSE branch len]...}
Compare two values and branch depending on the result of the comparison.
\begin{itemize}
\item A1 = index in variable table of left-side comparison variable
\item A2 = 0x01 for immediate comparison; 0x00 for variable comparison
\item A3 = immediate value to compare or index to variable to compare with (right side)
\item A4 = comparison function (0 = SUP; 2 = COMP; 3 = DIFF)
\item A5 = length of the IF branch of the conditional
\item A6 = length of the ELSE branch of the conditional (can be 0x00)
\end{itemize}
NB - the two length arguments are placed just before the code that their associated branches contain.
Either of the branches can be empty - an empty IF branch is perfectly valid.
The language has no JMP capabilities, so the IF and ELSE branches must directly follow the IF instruction.
The ... in the instruction definition represent source code.  There is no need to specify the
ending point of a branch - the length arguments handle the length.

\subsubsection{0xd0 - CALL [FUNIDX]}
Call a function.
\begin{itemize}
\item A1 = index in function table of function to call
\end{itemize}
NB - this is an overloaded instruction that is also used for function definition with a different
type signature

%%%%%%%%%%%
%MUTATION
%%%%%%%%%%%
\subsection{Mutation/settings}

%%%SET
\subsubsection{0xc0 - SET [VARIDX] 0x00 [VARIDX]}
\subsubsection{0xc0 - SET [VARIDX] 0x01 [LONGINT]}
Set the value of a variable.
\begin{itemize}
\item A1 = index of the variable to set
\item A2 = 0 to set to value of variable; 1 to set to immediate value
\item A3 = immediate value or variable index to set A1 to
\end{itemize}

%%%%INC/DEC
\subsubsection{0xc1 - DEC [VARIDX]}
Decrement a variable.
\begin{itemize}
\item A1 = index of the variable to decrement
\end{itemize}

\subsubsection{0xc2 - INC [VARIDX]}
Increment a variable
\begin{itemize}
\item A1 = index of the variable to increment
\end{itemize}

%TEAM
\subsubsection{0xdc - SET\_TEAM [VARIDX]}
Set the team number for this device.
\begin{itemize}
\item A1 = index of the variable which holds the team number
\end{itemize}

%HARNESS
\subsubsection{0xdd - SET\_HARNESS [INT]}
Set whether the harness is used or not in this game.
\begin{itemize}
\item A1 = 0 if harness is not used; 1 if harness is used
\end{itemize}






%%%%%%%%
%OUTPUT
%%%%%%%%
\subsection{Output}

%%MOTOR
\subsubsection{0xd3 - MOTOR [INT]}
Run the device motor.
\begin{itemize}
\item A1 = number of centiseconds to run the motor
\end{itemize}

%FLASH COLORS
\subsubsection{0xd4 - FLASH\_RED [INT]}
Flash a red light
\begin{itemize}
\item A1 = ??? 
\end{itemize}

\subsubsection{0xd5 - FLASH\_GREEN [INT]}
Flash a green light
\begin{itemize}
\item A1 = ???
\end{itemize}

%%%%%SND
\subsubsection{0xc5 - SND [0x00 | 0x01] [RESIDX] }
Play a sound.
\begin{itemize}
\item A1 = 0 for regular play; 1 for priority play???????
\item A2 = the index of the resource to display.  Must be a sound (\texttt{0x53,...}). 
\end{itemize}

%%IR
\subsubsection{0xc6 - IR}
Flash the IR transmitter in the gun.

%%%ANIM
\subsubsection{0xcb - ANIM [RESIDX]}
Display an animation on the HUD.  (See \ref{sec:animtab} for a list of resource constants;
see \ref{sec:resourcetable} for information about the resource table.)
\begin{itemize}
\item A1 = the index of the resource to display.  Must be an animation (\texttt{0x41,...}).
\end{itemize}

\subsubsection{0xcb - ANIM\_LOOP [RESIDX]}
Loop an animation on the HUD.  (See \ref{sec:animtab} for a list of resource constants;
see \ref{sec:resourcetable} for information about the resource table.)
\begin{itemize}
\item A1 = the index of the resource to display.  Must be an animation (\texttt{0x41,...}).
\end{itemize}


%ANIM_OFF
\subsubsection{0xdf - ANIM\_OFF}
TODO - what does this do???
Turn off (the????) animation on the HUD.

%%%LED
\subsubsection{0xda - LED\_ON [INT] [0x00 | 0x01]}
Turn on the LEDs on the harness.
\begin{itemize}
\item A1 = Length of time to turn on LED (or length of one-half of an on-off cycle)
\item A2 = 0 to blink once; 1 to blink repeatedly until LED\_OFF is called
\end{itemize}

\subsubsection{0xd7 - LED\_OFF}
Stop the LEDs on harness from blinking.



%%%DIGIT
\subsubsection{0xcd - HUD\_DIGIT [0x01/0x00] [INT/VARIDX] [0x01/0x00]}
Display a digit on the HUD. (between 0 and 19).  
\begin{itemize}
\item A1 = 0 for variable argument; 1 for constant argument
\item A2 = index of variable or immediate value to display
\item A3 = 0 for solid display; 1 for blinking display
\end{itemize}

\subsubsection{0xd6 - HUD\_DIGIT\_OFF}
Stop displaying a digit on the HUD.



%%%JAUGE
\subsubsection{0xce - HUD\_JAUGE [0x01/0x00] [INT/VARIDX] [0x01/0x00]}
Display a value on the gauge.  Valid values are between 1 and 6.  Anything greater
than 6 will cause the gauge to display a value of 0.  
\begin{itemize}
\item A1 = 0 for variable argument; 1 for constant argument
\item A2 = index of variable or immediate value to display
\item A3 = 0 for solid display; 1 for blinking display
\end{itemize}


%%%ICON
\subsubsection{0xcf - HUD\_ICON [0x01/0x00] [ICONIDX] [0x01/0x00]}
Modify the display state of one of the HUD icons. 
\begin{itemize}
\item A1 = 0 to turn off; 1 to turn on
\item A2 = icon to modify (see table \ref{sec:iconconstants})
\begin{itemize}
\item \texttt{0x00 = ubiconnect}
\item \texttt{0x01 = power}
\item \texttt{0x02 = LIFE}
\item \texttt{0x03 = BULLET}
\item \texttt{0x04 = GOAL}
\end{itemize}
\item A3 = 0 for solid display; 1 for blinking display
\end{itemize}


%%%%%%%%%%%%%
%RFID
%%%%%%%%%%%%%
\subsection{RFID commands}

\subsubsection{0xc8 - RFID\_SCAN [VARIDX]}
Perform a RFID scan.
\begin{itemize}
\item A1 = index of the variable in which to store the status of the scan.  Will be set to 0 
		upon failure, 1 upon success.
\end{itemize}

\subsubsection{0xde - RFID\_TYPE\_MAJOR [VARIDX]}
Get the type of the base scanned.
\begin{itemize}
\item A1 = index of the variable in which to store the type
\end{itemize}

\subsubsection{0xd9 - RFID\_TYPE\_MINOR [VARIDX]}
Get the specific ID of the base scanned (ie, is it T-Base 1 or T-Base 2).
\begin{itemize}
\item A1 = index of the variable in which to store the type
\end{itemize}

\section{Bytecode table}
\begin{center}
  \begin{tabular}{| c | c | }
    \hline
    Source symbol & Bytecode \\ \hline \hline
    ANIM 			& \texttt{0x41}  \\ \hline
    ANIM\_LOOP 		& \texttt{0xd8}  \\ \hline
    ANIM\_OFF 		& \texttt{0xdf}  \\ \hline
    CALL 			& \texttt{0xd0}  \\ \hline
    DEC 			& \texttt{0xc1}  \\ \hline
    FIRST\_STATE 	& \texttt{0xd2}  \\ \hline
    FLASH\_GREEN 	& \texttt{0xd5}  \\ \hline
   	FLASH\_RED 		& \texttt{0xd4}  \\ \hline
    FUNCTION 		& \texttt{0xd0}  \\ \hline
    HUD\_DIGIT 		& \texttt{0xcd}  \\ \hline
    HUD\_DIGIT\_OFF 	& \texttt{0xd6}  \\ \hline
    HUD\_ICON 		& \texttt{0xcf}  \\ \hline
    HUD\_JAUGE 		& \texttt{0xce}  \\ \hline
    IF 				& \texttt{0xc4}  \\ \hline
    INC 			& \texttt{0xc2}  \\ \hline
    IR 				& \texttt{0xc6}  \\ \hline
    LED\_OFF 		& \texttt{0xd7}  \\ \hline
    LED\_ON 			& \texttt{0xca}  \\ \hline
    MOTOR 			& \texttt{0xd3}  \\ \hline
    RFID\_SCAN 		& \texttt{0xc8}  \\ \hline
    RFID\_TYPE\_MAJOR & \texttt{0xde}  \\ \hline
    RFID\_TYPE\_MINOR & \texttt{0xd9}  \\ \hline
    SET 			& \texttt{0xc0}  \\ \hline
    SET\_HARNESS 	& \texttt{0xdd}  \\ \hline
    SET\_TEAM 		& \texttt{0xdc}  \\ \hline
    SND 			& \texttt{0xc5}  \\ \hline
    STATE 			& \texttt{0xc7}  \\ \hline
    TIMER		 	& \texttt{0xc9}  \\ \hline
    VAR 			& \texttt{0xcc}  \\ \hline
  \end{tabular}
\end{center}


\section{Constants}
This section contains tables of all of the constants that can appear in BTASM files.
Some of these are mapped directly onto what they represent; others create entries in 
integer-addressed tables that map from integers to the item represented by the bytecode.

\subsection{Animation constants}
\label{sec:animtab}
\begin{center}
  \begin{tabular}{| c | c || c | }
    \hline
    Source symbol & Table bytecode & Description \\ \hline \hline
    AGB1 & \texttt{0x41, 0x47, 0x42, 0x31, 0x00, 0x00} & ???  \\ \hline
    AGB2 & \texttt{0x41, 0x47, 0x42, 0x32, 0x00, 0x00} & ???  \\ \hline
    AGB3 & \texttt{0x41, 0x47, 0x42, 0x33, 0x00, 0x00} & ???  \\ \hline
    AGB4 & \texttt{0x41, 0x47, 0x42, 0x34, 0x00, 0x00} & ???  \\ \hline
    AMED & \texttt{0x41, 0x4d, 0x45, 0x44, 0x00, 0x00} & ???  \\ \hline
    AOUT & \texttt{0x41, 0x4f, 0x55, 0x54, 0x00, 0x00} & ???  \\ \hline
    ARAM & \texttt{0x41, 0x52, 0x41, 0x4d, 0x00, 0x00} & ???  \\ \hline
    ASHT & \texttt{0x41, 0x53, 0x48, 0x54, 0x00, 0x00} & ???  \\ \hline
    AUBI & \texttt{0x41, 0x44, 0x42, 0x49, 0x00, 0x00} & ???  \\ \hline
  \end{tabular}
\end{center}
NB - The table bytecodes are used in the resource block to enable a given resource in the gun 
environment; the actual value used to refer to the resource is dependent on its position in this
table.  (See section \ref{sec:resourcetable}).
	
\subsection{Sound constants}
\label{sec:sndtab}
\begin{center}
  \begin{tabular}{ | c | c || c | }
    \hline
    Source symbol & Table bytecode & Description \\ \hline \hline
    ASSIST\_BACKINGAME & \texttt{0x53, 0x44, 0x30, 0x32, 0x00, 0x00} & ???  \\ \hline
    ASSIST\_BASE1 & \texttt{0x53, 0x44, 0x30, 0x39, 0x00, 0x00} & ???  \\ \hline
    ASSIST\_BASE2 & \texttt{0x53, 0x44, 0x31, 0x30, 0x00, 0x00} & ???  \\ \hline
    ASSIST\_BASE3 & \texttt{0x53, 0x44, 0x31, 0x31, 0x00, 0x00} & ???  \\ \hline
    ASSIST\_BASE4 & \texttt{0x53, 0x44, 0x31, 0x32, 0x00, 0x00} & ???  \\ \hline    
    ASSIST\_SCANAMMO & \texttt{0x53, 0x44, 0x31, 0x33, 0x00, 0x00} & ???  \\ \hline
    ASSIST\_SCANLIFE & \texttt{0x53, 0x44, 0x31, 0x34, 0x00, 0x00} & ???  \\ \hline
    ASSIST\_UBICONNECT & \texttt{0x53, 0x44, 0x31, 0x35, 0x00, 0x00} & ???  \\ \hline
    BIP & \texttt{0x53, 0x43, 0x30, 0x32, 0x00, 0x00} & ???  \\ \hline
    DEAD & \texttt{0x53, 0x44, 0x30, 0x33, 0x00, 0x00}  & ???  \\ \hline
    EMPTY & \texttt{0x53, 0x57, 0x32, 0x32, 0x00, 0x00} & ???  \\ \hline
    HURT & \texttt{0x53, 0x43, 0x30, 0x35, 0x00, 0x00} & ``Ungh"  \\ \hline
	OK & \texttt{0x53, 0x43, 0x31, 0x30, 0x00, 0x00} & ``OK!"  \\ \hline	
    RELOAD & \texttt{0x53, 0x57, 0x31, 0x32, 0x00, 0x00} & ???  \\ \hline
	RELOAD\_CLIP & \texttt{0x53, 0x57, 0x34, 0x32, 0x00, 0x00} & ???  \\ \hline
	RESPAWN & \texttt{0x53, 0x43, 0x30, 0x37, 0x00, 0x00} & ???  \\ \hline	
	SC11 & \texttt{0x53, 0x43, 0x31, 0x31, 0x00, 0x00} & ???  \\ \hline      
	SCAN\_BAD & \texttt{0x53, 0x43, 0x30, 0x38, 0x00, 0x00} & ???  \\ \hline
    SCAN\_GOOD & \texttt{0x53, 0x43, 0x30, 0x39, 0x00, 0x00} & ???  \\ \hline
    SG01 & \texttt{0x53, 0x47, 0x30, 0x31, 0x00, 0x00} & ???  \\ \hline
    SG02 & \texttt{0x53, 0x47, 0x30, 0x32, 0x00, 0x00} & ???  \\ \hline
    SG03 & \texttt{0x53, 0x47, 0x30, 0x33, 0x00, 0x00} & ???  \\ \hline
    SG04 & \texttt{0x53, 0x47, 0x30, 0x34, 0x00, 0x00} & ???  \\ \hline  
    SHOOT & \texttt{0x53, 0x57, 0x35, 0x36, 0x00, 0x00} & ``Pew"  \\ \hline
    START & \texttt{0x53, 0x43, 0x30, 0x33, 0x00, 0x00} & ???  \\ \hline
  \end{tabular}
\end{center}
The table bytecodes are used in the resource block to enable a given resource in the gun 
environment; the actual value used to refer to the resource is dependent on its position in this
table.  (See section \ref{sec:resourcetable}).	


%%%%%%%%%%%%%%%%%%
%COMP
%%%%%%%%%%%%%%%%%%
\subsection{Comparison constants}
\label{sec:compconsts}
\begin{center}
  \begin{tabular}{ | c | c || c | }
    \hline
    Source symbol & Bytecode & Description \\ \hline \hline
    SUP & \texttt{0x00} & $>$  \\ \hline
    INF & \texttt{0x01} & $<$  \\ \hline
    COMP & \texttt{0x02} & ==  \\ \hline
    DIFF & \texttt{0x03} & !=  \\ \hline
    
  \end{tabular}
\end{center}

%%%%%%%%%%%%%%%%
%VARATTR
%%%%%%%%%%%%%%%%
\subsection{Variable attribute constants - \texttt{VARATTR}}
\label{sec:varattrconsts}
\begin{minipage}{\linewidth}
\begin{center}
  \begin{tabular}{ | c | c || c | }
    \hline
    Source symbol & Bytecode & Description \\ \hline \hline
    local\footnote{Local variables are declared without an identifier in the 
    	BTASM source language.} & \texttt{0x00} & On-device  \\ \hline
    SEND & \texttt{0x01} & Sent to GM  \\ \hline
    RECEIVE & \texttt{0x02} & Updated by GM throughout the game\footnote{The 	
    	\texttt{DATA\_CHANGE} event occurs when the GM updates a variable.  It can be ignored by 
    	the current state.}\\ \hline
    CONFIG & \texttt{0x03} & Set by GM at beginning of game\\ \hline
  \end{tabular}
\end{center}
\end{minipage}


%%%%%%%%%%%%%%%
%EVENT TYPE
%TODO - check TIMER and TICK and ANIM_FINISHED actions - ENTER_STATE, once or always called??
%%%%%%%%%%%%%%%
\subsection{Event type constants}
\label{sec:eventtypeconsts}
\begin{minipage}{\linewidth}
\begin{center}
  \begin{tabular}{ | c | c || c | }
    \hline
    Source symbol & Bytecode & Description \\ \hline \hline
    BUTTON\_1\_JUST\_PRESSED	& \texttt{0x00} & HUD button pressed  \\ \hline
    BUTTON\_2\_JUST\_PRESSED 	& \texttt{0x01} & Trigger just pressed  \\ \hline
    BUTTON\_3\_JUST\_PRESSED 	& \texttt{0x02} & RFID scan button just pressed  \\ \hline
    TIMER					 	& \texttt{0x09} & \texttt{TIMER} fired\footnote{
    					The timers are not state-specific; the current timer will cause a TIMER event
    					in whatever state the device is currently in.}  \\ \hline
    TICK					 	& \texttt{0x0a} & Called on each ``tick" of the clock\footnote{ 
    					Ticks are very fast - practically, a quick timer will probably work just 
    					as well.}  \\ \hline
    HIT						 	& \texttt{0x0b} & Shot by another gun  \\ \hline
    ENTER\_STATE			 	& \texttt{0x0c} & Call upon entering a state\footnote{ 
    					Called every time a state is entered, not just the first time.???} \\ \hline
    ANIM\_FINISHED			 	& \texttt{0x0d} & Animation on HUD completed.  \\ \hline
    DATA\_CHANGE 				& \texttt{0x0f} & GM has updated the \texttt{RECEIVE} variables.  
    					\\ \hline
  \end{tabular}
\end{center}
\end{minipage}

%%%%%%%%%%%%%%%
%ICON
%%%%%%%%%%%%%%%
\subsection{Icon constants}
\label{sec:iconconstants}
\begin{minipage}{\linewidth}
\renewcommand{\thefootnote}{\thempfootnote}
\begin{center}
  \begin{tabular}{ | c | c || c | }
    \hline
    Source symbol & Bytecode	 & Description \\ \hline \hline
    ubiconnect\footnote{Not guarnateed to behave as expected; should only be controlled by device 
   		 internal routines} 	& \texttt{0x00} & UbiConnect icon \\ \hline
    power\footnotemark[\value{footnote}] 		& \texttt{0x01} & Lightning bolt \\ \hline
    LIFE						& \texttt{0x02} & Plus sign  \\ \hline
    BULLET 						& \texttt{0x03} & Green bullet  \\ \hline
    GOAL 						& \texttt{0x04} & Green two-way arrow  \\ \hline
  \end{tabular}
\end{center}
\end{minipage}

%%%%%%%%%%%%%%%
%RFID major
%%%%%%%%%%%%%%%
\subsection{RFID\_SCAN\_MAJOR base constants}
\label{sec:rfidconstants}
\begin{minipage}{\linewidth}
\renewcommand{\thefootnote}{\thempfootnote}
\begin{center}
  \begin{tabular}{ | c | c || c | }
    \hline
    Source symbol & Bytecode	 & Description \\ \hline \hline
    RFID\_LIFE\_PACK	& \texttt{0x03}	& Any Med-Kit  \\ \hline
    RFID\_AMMO\_PACK	& \texttt{0x04}	& Any ammo pack  \\ \hline
    RFID\_BASE\_PACK	& \texttt{0x05}	& Any T-Base  \\ \hline
  \end{tabular}
\end{center}
\end{minipage}
%%%%%%%%%%%%%%%
%RFID minor
%%%%%%%%%%%%%%%
\subsection{RFID\_SCAN\_MINOR base constants}
\label{sec:rfidconstants}
\begin{minipage}{\linewidth}
\renewcommand{\thefootnote}{\thempfootnote}
\begin{center}
  \begin{tabular}{ | c | c || c | }
    \hline
    Source symbol & Bytecode	 & Description \\ \hline \hline
   	RFID\_BASE1 		& \texttt{0x00} & T-Base 1 \\ \hline
   	RFID\_AMMO1 		& \texttt{0x00} & Ammo pack 1 (4-bullet pack) \\ \hline
  \end{tabular}
\end{center}
\end{minipage}

\section{Tables}
BTASM bytcode creates a number of tables on the device that are used during the game.  These are:
\begin{itemize}
\item The resource table
\item The variable table
\item (The function table)
\item (The state table)
\end{itemize}

The tables that are not parenthesized appear in the above order in the bytecode.  
The resource table must come first, followed immediately by the variable table.  The function
and state tables are generated from the \texttt{FUNCTION} and \texttt{STATE} commands.  They do
not appear as specific tables.

These tables all map from integers to the item at hand.  The table to be read from
at any given point is determined by the command being processed.  For example, a 
\texttt{SET}
command will read from the variable table, while a \texttt{GOTO} command will read from the
state table.

\subsection{Resource table}
\label{sec:resourcetable}
The resource table is the first item in a BTASM bytecode or source file.  It is formatted as 
follows:

\begin{itemize}
\item A byte containing the number of resources
\item A list of resource byte codes
\end{itemize}
\begin{figure}[h]
\begin{lstlisting}
<number of resources>
<bytecode for first resource>
<bytecode for second resource>
...
<bytecode for final resource>
\end{lstlisting}
\caption{Layout of a resource table} 
\end{figure}

The byte codes for specific resources can be found in the 
Within in the program, resources are referred to by their indices in the resource table.  The
location of each index in the table is determined by the order of resource bytecodes in the
table.  (See Figure~\ref{Resource table})
\begin{figure}[h]
\begin{lstlisting}
0x02,								-- 2 resources
0x53, 0x43, 0x30, 0x35, 0x00, 0x00, -- HURT
0x53, 0x43, 0x30, 0x33, 0x00, 0x00,	-- START
...
0xd0, 0x00, 0x06, 			-- function declaration 
							--   (6 bytes long)
0xc5, 0x00, 0x00,			-- SND HURT
0xc5, 0x01, 0x00,			-- SND START
--*end of function*
...
\end{lstlisting}
\caption{\label{Resource table} example code} 
\end{figure}

There are two types of resources: animation resources (begin with \texttt{A} in the BTASM source
language and \texttt{0x41} in the BTASM bytecode); and sound resources (begin with \texttt{0x53}
in the bytecode.  These can be added interchangeably in the resource table; animations must be
used with \texttt{ANIM}, while sounds must be used with \texttt{SND}.


\subsection{Variable table}
\label{sec:vartable}
The variable table is created by a sequence of \texttt{VAR} commands at the 

\subsection{Function/state tables}
\label{sec:funstatetables}

\chapter{The Game Master}
The bytecode on the guns is useless without the Game Master to set up and control the games.  While
the majority of the gameplay work is done on the guns in the course of an actual round, the computer
can play an essential role, especially in games where players change roles, or aspects of the 
gamplay change depending on the current state of the game.  (As an example, take Counter Strike, 
where the placement of the bomb changes the player's immediate goals; or tag, where the person who
is ``it" has a different set of goals than everyone else, and is in a different state.)

\section{Creating a new game}
Creating a new game is straightforward, though there are some pitfalls if one is not careful.  I've
outlined the process for creating a new game more thoroughly 
\chapter{Examples of BTASM Source Code}

\section{Arithmetic}
Conspicuously absent from the BTASM language is any way to do arithmetic.  This is typically 
unnecessary in the context of laser tag games -- however, it is perhaps useful to see how one could
add arithmetic functionalities.  
These arithmetic functions are not foolproof - it is certainly possible for an event to occur that
causes the values in these functions to be blown.  The effects of timer interrupts on running 
functions has not yet been tested.???

\subsection{Addition/Subtraction}
These functions are analogous, and could be designed in other ways.  This design requires two 
specially declared argument variables, and returns its value in the first of these argument 
variables.  The subtraction function returns 1 in its second argument if there was an underflow.
\\\\
\begin{figure}[h]
\begin{lstlisting}
VAR arg1	//Argument passing variables
VAR arg2
VAR add_temp1	//Special temporary variables
VAR add_temp2	//for the add function


FUNCTION add

	SET add_temp1 arg1
	SET add_temp2 arg2
	add_h
	SET arg1 add_temp1
	
END_FUNCTION

//Helper function
FUNCTION add_h

	IF add_temp2 SUP 0
		INC add_temp1
		DEC add_temp2
		add_h
	END_IF
	
END_FUNCTION
\end{lstlisting}
\caption{An addition function} 
\end{figure}

\begin{figure}[h]
\begin{lstlisting}
VAR arg1	//Argument passing variables
VAR arg2
VAR sub_temp1	//Special temporary variables
VAR sub_temp2	//for the sub function


FUNCTION add

	SET sub_temp1 arg1
	SET sub_temp2 arg2
	sub_h
	SET arg1 sub_temp1
	SET arg2 sub_temp2
	
END_FUNCTION

//Helper function
FUNCTION sub_h

	IF sub_temp2 SUP 0
		IF sub_temp1 SUP 0
			DEC sub_temp1
			DEC sub_temp2
			add_h
		ELSE
			SET sub_temp2 1
		END_IF
	END_IF
	
END_FUNCTION
\end{lstlisting}
\caption{A subtraction function (that prevents underflow)} 
\end{figure}
%Notice that, though these functions are recursive, there is no stack to blow, so there is no
%slowdown due to tracking out through a deeply-nested stack.

\subsection{Multiplication/Division}
Multiplication and division are more difficult.  For these, we assume that we have the \texttt{add}
and \texttt{sub} functions declared above available, and that\texttt{arg1} and \texttt{arg2} are
the argument variables.  The multiplication function returns its value in the first argument; the
division function returns the quotient in the second argument and the remainder in the first 
argument.

\begin{figure}[h]
\begin{lstlisting}
VAR arg1	//Argument passing variables
VAR arg2
VAR mult_temp1	//Special temporary variables
VAR mult_temp2	//for the mult function
VAR mult_temp3

FUNCTION mult

	SET mult_temp1 arg1
	SET mult_temp2 arg2
	SET mult_temp3 0
	mult_h
	SET arg1 mult_temp3
	
END_FUNCTION
	
	
FUNCTION mult_h

	IF mult_temp2 SUP 0
		SET arg1 mult_temp3
		SET arg2 mult_temp1
		DEC mult_temp2
		add
		SET mult_temp3 arg1
		mult_h
	END_IF
	
END_FUNCTION
\end{lstlisting}
\caption{A multiplication function} 
\end{figure}



\begin{figure}[h]
\begin{lstlisting}
VAR arg1	//Argument passing variables
VAR arg2
VAR mult_temp1	//Special temporary variables
VAR mult_temp2	//for the mult function
VAR mult_temp3

FUNCTION mult

	SET mult_temp1 arg1
	SET mult_temp2 arg2
	SET mult_temp3 0
	mult_h
	SET arg1 mult_temp3
	
	
END_FUNCTION
	
	IF mult_temp2 SUP 0
		SET arg1 mult_temp3
		SET arg2 mult_temp1
		DEC mult_temp2
		add
		SET mult_temp3 arg1
	END_IF
	
END_FUNCTION
\end{lstlisting}
\caption{A multiplication function} 
\end{figure}

From this point, it would certainly be possible to create other, more complicated arithmetic
functions.  This is not usually a useful exercise, however -- in practice, it makes more sense to
have a set of \texttt{SEND} and \texttt{RECEIVE} variables that communicate with the GM and do
the arithmetic on a machine designed to perform addition, subtraction, multiplication and division.

\section{Timers}
The BTASM language only has provisions for 2.55 second timers.  This may not be enough for what is
required in a more complicated game.  This example demonstrates how to create a longer timer.
This is a convenient way to create a countdown, and is the basic method I use to allow for longer
arming and diffusing times in the Counter Strike case study.

\section{Next steps}
If you understand these examples, the best way to get a better grasp of the language is to look at
more extensive source files.  The files that are provided by UbiSoft are not that easy to read --
they are not indented and there is too much white space.  The btasm compiler distribution includes
a script, beautifier.pl, that blindly indents and removes extra lines from BTASM source files.

The BTASM source files are helpful for figuring out how to write a program in the limited 
device environment of the gun. 

\begin{figure}[h]
\begin{lstlisting}
VAR timer_len	//Timer length in seconds

STATE init
FIRST_STATE

EVENT ENTER_STATE
    TIMER 100			//1 second timer
    SET timer_len 10	//10 times (so 10 seconds)
END_EVENT

EVENT TIMER
    IF timer_len SUP 0
	    DEC timer_len
	    HUD_DIGIT timer_len //Create a countdown timer
    END_IF
END_EVENT

END_STATE
	
\end{lstlisting}
\caption{A longer timer, with a countdown} 
\end{figure}

\chapter{Counter Strike - A Case Study}
\end{document}
